Documentation: Add support for deprecated/experimental messages #81458

dalexeev · 2023-09-08T15:36:30Z

Add support for deprecated/experimental messages to core and GDScript. See:

## my_func desc.
## @deprecated: Use [method another] instead.
func my_func():
    pass

Bugsquad edit, fixes: "Deprecated" needs to be more visible in the documentation godot-docs#7900
Production edit: closes godotengine/godot-roadmap#71

YuriSizov · 2023-09-08T17:52:12Z

This would be a breaking change for the XML format. We should find a way to avoid that.

dalexeev · 2023-09-08T20:25:15Z

We can use two attributes, bool and string, just like in DocData structures. But it's less compact. Or we can add compatibility code for the old boolean attributes, which will allow the old XMLs to be read, but on write they will be saved in the new format. It's funny if we deprecate the is_deprecated attribute.

raulsntos · 2023-09-10T11:16:00Z

I love this, we've been generating generic messages like This method is deprecated in the generated C# API and now we'll be able to provide something more informative.

I noticed there were some empty deprecation messages. Should we try to avoid empty messages or is it intended that some messages will be empty? We can still provide the generic message in C# in these cases, but I think it'd be better to provide a better message. I'm not suggesting to fill all the messages in this PR, it could be a follow-up.

I'm not sure how useful it is for experimental API though, it seems all the messages are empty in this PR. I also don't know what we would write here other than a generic This API is experimental and may change in the future. We also wouldn't be able to use these messages in C#, the [Experimental] attribute doesn't allow providing a message, but that shouldn't block this if it's still useful.

modules/gltf/doc_classes/GLTFDocument.xml

raulsntos · 2023-09-10T11:23:34Z

doc/classes/SkeletonIK3D.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8" ?>
-<class name="SkeletonIK3D" inherits="Node" is_deprecated="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+<class name="SkeletonIK3D" inherits="Node" deprecated="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">


I think there was someone asking recently why this class was deprecated, worried that it will be removed without an alternative. Maybe we could add a message here that clarifies that a replacement will be provided in the future?

CC @godotengine/animation

dalexeev · 2023-09-10T11:32:39Z

I noticed there were some empty deprecation messages. Should we try to avoid empty messages or is it intended that some messages will be empty?

I think so, but I've left the messages empty for now. We should also think about default messages. Now I've added a neutral "This ... may be changed or removed in future versions.", but this should probably be different for Deprecated and Experimental and for engine and user code.

I'm not sure how useful it is for experimental API though, it seems all the messages are empty in this PR. I also don't know what we would write here other than a generic This API is experimental and may change in the future.

Probably yes, although I think that sometimes we can indicate problems when using the experimental API:

dalexeev · 2023-09-10T11:35:16Z

doc/class.xsd

@@ -273,8 +289,13 @@
 			</xs:sequence>
 			<xs:attribute type="xs:string" name="name" />
 			<xs:attribute type="xs:string" name="inherits" />
+			<!-- deprecated -->
+			<xs:attribute type="xs:float" name="version" use="optional" />


See Doctool: Remove version attribute from XML header #79092.

dalexeev · 2023-09-10T16:47:36Z

doc/tools/make_rst.py

+        deprecated_prefix = translate("Deprecated:")
+        if item.deprecated.strip() == "":
+            default_message = translate(f"This {item.definition_name} may be changed or removed in future versions.")
+            result += f"**{deprecated_prefix}** {default_message}\n\n"
+        else:
+            result += f"**{deprecated_prefix}** {format_text_block(item.deprecated.strip(), item, state)}\n\n"


Is there a way to use color in RST? This will probably require some changes to the site so that we can use:

:red:`Deprecated:"` Message.

or

.. deprecated:: Message.

Now it looks like this:

I only added this to the descriptions, not to the overviews.

rST doesn't support arbitrary colors (aside of raw HTML tags). You could use the .. danger:: adominition though, which appears in red.

See also #63079.

How to use color in text with ReStructured Text (rst2html.py) or how to insert HTML tags without blank lines?

AThousandShips

LGTM style and code wise

doc/classes/AnimationPlayer.xml

doc/classes/AnimationTree.xml

doc/classes/NavigationPolygon.xml

Calinou

Tested locally (rebased on top of master f317cc7), it mostly works as expected.

I can't get the deprecated/experimental reason messages to show up though:

extends Node2D

## Description.
##@deprecated: Test reason
var var1

##@experimental: Test reason 2
var var2

# Test comment (not a docblock).
##@deprecated: Test reason 3
func one() -> void:
	pass


##@experimental: Test reason 4
##Description.
func two() -> void:
	pass

dalexeev · 2024-02-13T06:23:07Z

@Calinou Looks like you were testing an older version:

dalexeev · 2024-02-13T09:47:31Z

I have completed self-review and testing. This initially small PR grew into a significant EditorHelp refactoring:

Add missing XML escaping in DocTools.
Rename "Theme Item" to "Theme Property" in various make_rst.py and editor_help.cpp messages for consistency. This does not break compatibility, the [theme_item] tag is left unchanged.
Fix a bug with [theme_item] navigation for external classes.
Unify blank lines for all Editor Help sections.
Fix theme property anchors.
Replace find() with find_char() for optimization.
Improve grouping of push_*() and pop() calls, add comments for consistency.
Fix usage of text append methods:
- class_desc->add_text() - Used to add text "as is".
- class_desc->append_text() - Used to append text that is guaranteed to contain only standard BBCodes.
- _add_text() - Used if the text can contain custom EditorHelp markup.
Add missing _fix_constant() and value color.
Improve detection of multiline descriptions for constants and enum elements.
Improve link for property overrides.

akien-mga

Looks great to me overall!

doc/classes/@GlobalScope.xml

doc/classes/AnimationPlayer.xml

doc/classes/InputEventJoypadButton.xml

doc/classes/MultiMesh.xml

akien-mga · 2024-02-15T11:10:51Z

doc/classes/SkeletonIK3D.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8" ?>
-<class name="SkeletonIK3D" inherits="Node" is_deprecated="true" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+<class name="SkeletonIK3D" inherits="Node" deprecated="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">


CC @godotengine/animation

akien-mga · 2024-02-15T11:17:21Z

We should probably find some consensus on how to documentation deprecated and experimental methods/properties, and apply it throughout the codebase (cc @godotengine/documentation).

Notably, how to document a method/property when it's deprecated because:

It doesn't do anything and we're just keeping it to avoid breaking API compat
It still does something but was replaced by a new method/property which should be referenced
It still does something but is no longer supported, and no alternative is given

We can now put information in the deprecated message, but there's still the main description to deal with. What should it contain? Should it be kept empty if all the relevant info is in the deprecation message? If so, should we change doc/tools/doc_status.py so it considers an empty description of a method/property with a deprecated message as fully documented?

doc/classes/TileMap.xml

Mickeon · 2024-02-15T11:59:33Z

I was taking a look. In my opinion, to make it extremely short:

The deprecated/experimental message should explain "why" and/or provide the better alternative(s);
The description should explain "what". Very, very briefly.
- I can't think of exceptions. Not saying what something is/was feels wrong to me.

_{Also these messages are not translatable now, are they?}

dalexeev · 2024-02-15T12:15:00Z

Also these messages are not translatable now, are they?

Yes, after merging this PR, some changes are needed in extract_classes.py.

As for the docs, I agree with you, but I think that in any case we will need a follow-up PR for adjustments. However, I'm ready to apply suggestions that we are already confident about.

Mickeon · 2024-02-15T12:35:06Z

I don't mind scouting across the class reference a second time as some form of standardization, post-merge. I got nothing better to do...

akien-mga · 2024-02-15T14:52:51Z

Thanks!

dalexeev added enhancement topic:core topic:gdscript documentation labels Sep 8, 2023

dalexeev added this to the 4.x milestone Sep 8, 2023

dalexeev force-pushed the doc-add-deprected-experimental-message branch from 962a286 to 402f0a8 Compare September 10, 2023 11:12

raulsntos reviewed Sep 10, 2023

View reviewed changes

dalexeev commented Sep 10, 2023

View reviewed changes

dalexeev force-pushed the doc-add-deprected-experimental-message branch from 402f0a8 to 4fde31e Compare September 10, 2023 16:32

dalexeev marked this pull request as ready for review September 10, 2023 16:34

dalexeev requested review from a team as code owners September 10, 2023 16:34

dalexeev commented Sep 10, 2023

View reviewed changes

AThousandShips mentioned this pull request Sep 11, 2023

"Deprecated" needs to be more visible in the documentation godotengine/godot-docs#7900

Closed

AThousandShips removed topic:core topic:gdscript labels Nov 10, 2023

YuriSizov added topic:core topic:gdscript labels Nov 13, 2023

dalexeev force-pushed the doc-add-deprected-experimental-message branch from 4fde31e to 0e04038 Compare February 12, 2024 15:03

AThousandShips approved these changes Feb 12, 2024

View reviewed changes

doc/classes/AnimationPlayer.xml Outdated Show resolved Hide resolved

doc/classes/AnimationTree.xml Outdated Show resolved Hide resolved

doc/classes/NavigationPolygon.xml Outdated Show resolved Hide resolved

dalexeev force-pushed the doc-add-deprected-experimental-message branch 2 times, most recently from cbd43ce to bf9b2a8 Compare February 12, 2024 21:25

Calinou reviewed Feb 12, 2024

View reviewed changes

dalexeev force-pushed the doc-add-deprected-experimental-message branch 2 times, most recently from 53d338a to eea19d6 Compare February 13, 2024 09:16

dalexeev force-pushed the doc-add-deprected-experimental-message branch from eea19d6 to 513a46f Compare February 13, 2024 11:04

akien-mga approved these changes Feb 15, 2024

View reviewed changes

Mickeon reviewed Feb 15, 2024

View reviewed changes

doc/classes/TileMap.xml Show resolved Hide resolved

Documentation: Add support for deprecated/experimental messages

af28f87

dalexeev force-pushed the doc-add-deprected-experimental-message branch from 513a46f to af28f87 Compare February 15, 2024 12:59

akien-mga modified the milestones: 4.x, 4.3 Feb 15, 2024

akien-mga merged commit be7229f into godotengine:master Feb 15, 2024
16 checks passed

dalexeev deleted the doc-add-deprected-experimental-message branch February 15, 2024 14:59

akien-mga mentioned this pull request Feb 15, 2024

Rework the auto translation system #87530

Merged

This was referenced Feb 15, 2024

Add extraction of deprecated/experimental messages godotengine/godot-editor-l10n#16

Merged

GDScript: Update deprecated/experimental docs godotengine/godot-docs#8972

Merged

Documentation: Treat deprecated/experimental members as documented #88401

Merged

Mickeon mentioned this pull request Feb 17, 2024

Update many Deprecated/Experimental descriptions for consistency #88443

Merged

raulsntos mentioned this pull request Feb 23, 2024

C#: Add deprecated message to generated bindings #88730

Merged

dalexeev mentioned this pull request May 2, 2024

Update class reference and doc comment markup documentation godotengine/godot-docs#9313

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation: Add support for deprecated/experimental messages #81458

Documentation: Add support for deprecated/experimental messages #81458

dalexeev commented Sep 8, 2023 •

edited by adamscott

Loading

YuriSizov commented Sep 8, 2023

dalexeev commented Sep 8, 2023

raulsntos commented Sep 10, 2023

raulsntos Sep 10, 2023

akien-mga Feb 15, 2024

dalexeev commented Sep 10, 2023

dalexeev Sep 10, 2023

dalexeev Sep 10, 2023

Calinou Sep 10, 2023 •

edited

Loading

dalexeev Sep 10, 2023

AThousandShips left a comment

Calinou left a comment

dalexeev commented Feb 13, 2024

dalexeev commented Feb 13, 2024 •

edited

Loading

akien-mga left a comment

akien-mga Feb 15, 2024

akien-mga commented Feb 15, 2024

Mickeon commented Feb 15, 2024 •

edited

Loading

dalexeev commented Feb 15, 2024

Mickeon commented Feb 15, 2024 •

edited

Loading

akien-mga commented Feb 15, 2024

Documentation: Add support for deprecated/experimental messages #81458

Documentation: Add support for deprecated/experimental messages #81458

Conversation

dalexeev commented Sep 8, 2023 • edited by adamscott Loading

YuriSizov commented Sep 8, 2023

dalexeev commented Sep 8, 2023

raulsntos commented Sep 10, 2023

raulsntos Sep 10, 2023

Choose a reason for hiding this comment

akien-mga Feb 15, 2024

Choose a reason for hiding this comment

dalexeev commented Sep 10, 2023

dalexeev Sep 10, 2023

Choose a reason for hiding this comment

dalexeev Sep 10, 2023

Choose a reason for hiding this comment

Calinou Sep 10, 2023 • edited Loading

Choose a reason for hiding this comment

dalexeev Sep 10, 2023

Choose a reason for hiding this comment

AThousandShips left a comment

Choose a reason for hiding this comment

Calinou left a comment

Choose a reason for hiding this comment

dalexeev commented Feb 13, 2024

dalexeev commented Feb 13, 2024 • edited Loading

akien-mga left a comment

Choose a reason for hiding this comment

akien-mga Feb 15, 2024

Choose a reason for hiding this comment

akien-mga commented Feb 15, 2024

Mickeon commented Feb 15, 2024 • edited Loading

dalexeev commented Feb 15, 2024

Mickeon commented Feb 15, 2024 • edited Loading

akien-mga commented Feb 15, 2024

dalexeev commented Sep 8, 2023 •

edited by adamscott

Loading

Calinou Sep 10, 2023 •

edited

Loading

dalexeev commented Feb 13, 2024 •

edited

Loading

Mickeon commented Feb 15, 2024 •

edited

Loading

Mickeon commented Feb 15, 2024 •

edited

Loading